GBAC by paulohtb6 · Pull Request #1584 · redpanda-data/docs

paulohtb6 · 2026-02-24T19:23:31Z

Description

Related PR to add Security to Admin API v2: redpanda-data/api-docs#60
Single sourcing to Cloud: redpanda-data/cloud-docs#536

This pull request introduces comprehensive documentation for Group-Based Access Control (GBAC) in Redpanda, detailing how permissions can now be assigned to OIDC groups in addition to individual users. It adds new conceptual and how-to guides, updates navigation, and describes configuration, usage patterns, and limitations for GBAC. It also documents new configuration properties relevant to group extraction from authentication tokens.

The most important changes are:

GBAC Documentation and How-to Guides:

Added a new how-to guide gbac.adoc under security/authorization, with detailed instructions, usage patterns, configuration, and examples for assigning groups to roles and creating group-based ACLs. [1] [2]
Added partials for UI-based group-to-role assignment (gbac-assign-group-role.adoc) and group ACL creation (gbac-create-group-acl.adoc). [1] [2]

Navigation and Discoverability:

Updated navigation (nav.adoc) to include GBAC under both Kubernetes and general security/authorization sections, making the new documentation easily discoverable. [1] [2]
Updated the main authorization index to mention group-based access control alongside ACLs and RBAC.

Release Notes and Feature Announcements:

Announced GBAC as a new feature in the release notes, summarizing its capabilities and usage patterns.
Documented two new configuration properties for GBAC: nested_group_behavior and oidc_group_claim_path.

OIDC Authentication Documentation:

Added a tip to the OIDC authentication documentation highlighting that GBAC can be used to assign permissions to groups, not just users.

Resolves DOC-1789
Review deadline: March 3rd

Page previews

Main doc - GBAC
Cluster Properties:
- oidc_group_claim_path
- nested_group_behavior
Authorization index
Audit logging
Audit logging samples
What's new

Checks

New feature
Content gap
Support Follow-up
Small fix (typos, links, copyedits, etc)

netlify · 2026-02-24T19:23:36Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`c2263bf`
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/69cb4d94d765d36925fd0a87
😎 Deploy Preview	https://deploy-preview-1584--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-02-24T19:23:39Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6aad09da-c2c5-475b-843e-af5fe27e1446

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch gbac

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nguyen-andrew

Looks good so far! Just some minor comments and questions

modules/manage/partials/gbac-dp.adoc

nguyen-andrew · 2026-02-25T22:51:32Z

modules/manage/partials/gbac-dp.adoc

@@ -0,0 +1,336 @@
+// tag::single-source[]
+
+Group-based access control (GBAC) builds on xref:manage:security/authorization/rbac.adoc[role-based access control (RBAC)] to simplify permission management at scale. Instead of assigning roles or ACLs to individual users, you assign them to OIDC groups managed by your identity provider (IdP). Users inherit permissions from all groups reported in their OIDC token claims, so onboarding and offboarding require no changes in Redpanda.


I wonder if we should mention OIDC earlier in the paragraph (like in the first sentence) so readers immediately understand that GBAC depends on OIDC being configured. I think the OIDC dependency could be easy to miss upfront until the reader reads further down (like the Prerequisites section).

modules/manage/partials/gbac-dp.adoc

modules/manage/partials/gbac-create-group-acl.adoc

nguyen-andrew · 2026-02-25T23:41:47Z

modules/manage/partials/gbac-dp.adoc

+Users with more than 200 group memberships in Azure AD receive a URL reference in their token instead of a list of group names. Redpanda does not follow that URL and cannot resolve groups in this case. Mitigation: filter token claims to include only the groups relevant to Redpanda.
+
+Nested groups::
+Redpanda does not recursively resolve nested group hierarchies. If group A contains group B, only the direct memberships reported in the token are used. Use `nested_group_behavior: suffix` to extract the last path segment from hierarchical group names when needed.


Adding a link to Customize token claim extraction#nested_group_behavior or the nested_group_behavior section in the cluster properties reference could be helpful here too, if possible.

modules/manage/partials/gbac-dp.adoc

modules/manage/pages/kubernetes/security/authorization/k-gbac.adoc

modules/get-started/pages/release-notes/redpanda.adoc

treevon

This looks good. The token extraction section is really nice with clear examples

treevon · 2026-03-03T20:43:28Z

modules/manage/partials/gbac-dp.adoc

+== Prerequisites
+
+* xref:manage:security/authentication.adoc#oidc[OIDC authentication] must be configured and enabled on your cluster.
+* Superuser access to configure cluster properties and manage ACLs.


nit - this is a prerequisite to enable OIDC, so should appear first

@treevon for Cloud should we just remove this superuser prereq?

@treevon since we don't have superuser in Cloud, can we remove (conditionalize this out) for Cloud?

@kbatuigas would you please conditionalize this out for Cloud docs?

Moved superuser prereq into conditional

modules/manage/partials/gbac-dp.adoc

treevon · 2026-03-03T20:47:05Z

modules/manage/partials/gbac-dp.adoc

+  --resource-pattern-type prefixed
+----
+
+If your groups use path-style names (with xref:reference:properties/cluster-properties.adoc#nested_group_behavior[`nested_group_behavior`] set to `none`), use the full path as the principal name:


I think we should move this to the section on claim extraction

nguyen-andrew

Looks good to me

# Conflicts: # modules/get-started/pages/release-notes/redpanda.adoc

modules/manage/partials/gbac-dp.adoc

modules/ROOT/nav.adoc

modules/manage/partials/gbac-dp.adoc

graham-rp

We ended up removing the --group flags on rpk security role

graham-rp · 2026-03-30T14:54:59Z

modules/manage/partials/gbac-dp.adoc

+
+[,bash]
+----
+rpk security role assign <role-name> --group <group-name>


We ended up pivoting to using ACLs directly in rpk. This gets rid of --group in favor of the principal directly, so rpk security role assign <role-name> --principal Group:<group-name>

modules/manage/partials/gbac-dp.adoc

micheleRP · 2026-03-30T19:03:46Z

modules/manage/pages/audit-logging/audit-log-samples.adoc

+.Authorization matched on a group ACL
+[%collapsible]
+====
+This example shows an API Activity event (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:manage:security/authorization/gbac.adoc[].


Suggested change

This example shows an API Activity event (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:manage:security/authorization/gbac.adoc[].

This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:manage:security/authorization/gbac.adoc[].

micheleRP · 2026-03-30T19:34:56Z

modules/manage/partials/gbac-dp.adoc

+
+--
+. From *Security* on the left navigation menu, select the *Groups* tab.
+. 


@kbatuigas reminder about these steps. We can update later if necessary

micheleRP · 2026-03-30T19:37:12Z

modules/manage/partials/gbac-create-group-acl.adoc

@@ -0,0 +1,13 @@
+To create an ACL for an OIDC group in {ui}:


Style suggestion: The section is titled "Create group-based ACLs" but the steps navigate to the Roles tab. The NOTE explaining why ("{ui} assigns ACLs through roles") comes after the procedure on line 13, which may confuse users who expect to land on an ACL-related page.

Consider adding a brief lead-in sentence before the numbered steps:

In {ui}, group-based ACLs are managed through roles. To create an ACL for an OIDC group:

The NOTE at the end can stay as supplementary detail.

modules/manage/partials/gbac-dp.adoc

micheleRP · 2026-03-30T19:40:02Z

Style suggestion — modules/manage/pages/security/authorization/index.adoc line 8:

"Authentication grants permission to interact with Redpanda resources" conflates authentication with authorization. Authentication verifies identity, not permissions.

Suggest:

Authentication verifies who a principal is. Authorization controls what that principal can do once authenticated.

micheleRP

thanks @kbatuigas!

local-antora-playbook.yml

modules/manage/partials/gbac-dp.adoc

david-yu · 2026-03-31T03:57:48Z

Is GBAC an enterprise only feature? if so, we should call that out and add to Enterprise features list.

kbatuigas · 2026-03-31T04:02:58Z

Is GBAC an enterprise only feature? if so, we should call that out and add to Enterprise features list.

@david-yu Yes -- I have a pending commit to https://deploy-preview-1584--redpanda-docs-preview.netlify.app/current/get-started/licensing/overview/#self-managed, but I have not yet received confirmation on what the behavior is when the license expires.

david-yu · 2026-03-31T04:24:46Z

Is GBAC an enterprise only feature? if so, we should call that out and add to Enterprise features list.

@david-yu Yes -- I have a pending commit to https://deploy-preview-1584--redpanda-docs-preview.netlify.app/current/get-started/licensing/overview/#self-managed, but I have not yet received confirmation on what the behavior is when the license expires.

@nguyen-andrew or @treevon Could you confirm the behavior upon license expiry? This is what i got from Claude so far

 When a license expires, feature_table::should_sanction() returns true (src/v/features/feature_table.cc:768-778). The effects:

 1. New group-principal ACL creation is rejected with an error message like: "A Redpanda Enterprise Edition license is required to create an ACL with a group
  principal." (src/v/features/enterprise_feature_messages.h:115-119)
 2. Existing ACLs/configuration remain in place — the sanction blocks new operations, not existing state

kbatuigas · 2026-03-31T04:42:28Z

Is GBAC an enterprise only feature? if so, we should call that out and add to Enterprise features list.

@david-yu Yes -- I have a pending commit to https://deploy-preview-1584--redpanda-docs-preview.netlify.app/current/get-started/licensing/overview/#self-managed, but I have not yet received confirmation on what the behavior is when the license expires.

@nguyen-andrew or @treevon Could you confirm the behavior upon license expiry? This is what i got from Claude so far
 When a license expires, feature_table::should_sanction() returns true (src/v/features/feature_table.cc:768-778). The effects:

 1. New group-principal ACL creation is rejected with an error message like: "A Redpanda Enterprise Edition license is required to create an ACL with a group
  principal." (src/v/features/enterprise_feature_messages.h:115-119)
 2. Existing ACLs/configuration remain in place — the sanction blocks new operations, not existing state

@nguyen-andrew @treevon @david-yu This PR must be merged tonight in order for us to prep the release PR tomorrow. I'll do that now, but I posted in the #gbac channel in Slack so I can check for a response there, or try and add a quick doc update tomorrow. cc @JakeSCahill if we get confirmation on the license expiry tomorrow, could we still add that in to the release PR before you have to merge it?

Adds enterprise license requirement banner to the Group controller documentation as GBAC (Group-Based Access Control) is an enterprise feature that requires OIDC authentication. Addresses PR feedback from david-yu requesting the license banner based on the pattern established in PR redpanda-data#1584. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

paulohtb6 requested a review from a team as a code owner February 24, 2026 19:23

paulohtb6 force-pushed the gbac branch from ab67eab to 1cab678 Compare February 24, 2026 19:24

paulohtb6 changed the title ~~Gbac~~ GBAC Feb 24, 2026

paulohtb6 force-pushed the gbac branch from cecb2f4 to 38072b1 Compare February 24, 2026 20:23

paulohtb6 requested a review from nguyen-andrew February 24, 2026 20:25

nguyen-andrew reviewed Feb 26, 2026

View reviewed changes

treevon approved these changes Mar 3, 2026

View reviewed changes

nguyen-andrew approved these changes Mar 9, 2026

View reviewed changes

paulohtb6 and others added 8 commits March 20, 2026 18:43

security: add gbac docs

8197505

add prop reference

dc2dae6

add what's new

33fd2a8

# Conflicts: # modules/get-started/pages/release-notes/redpanda.adoc

fix

29c73fc

address revieww comments

ee85e23

add diagram

bd663d0

Adjust naming

948da37

Apply suggestions from SME review

191344f

kbatuigas force-pushed the gbac branch from d421239 to 191344f Compare March 21, 2026 01:46

kbatuigas added 4 commits March 23, 2026 12:15

Move conceptual sections and add Admin v2 links

cc0d637

Increase default width for Mermaid diagram

7787674

Add GBAC info on audit logging

5cf510c

Add troubleshooting section

edc9719

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/ROOT/nav.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Show resolved Hide resolved

micheleRP reviewed Mar 25, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Outdated Show resolved Hide resolved

graham-rp reviewed Mar 30, 2026

View reviewed changes

Incorporate rpk changes

0940dc7

micheleRP reviewed Mar 30, 2026

View reviewed changes

Retrigger Netlify build

ec98020

micheleRP reviewed Mar 30, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Show resolved Hide resolved

micheleRP approved these changes Mar 30, 2026

View reviewed changes

kbatuigas reviewed Mar 30, 2026

View reviewed changes

local-antora-playbook.yml Outdated Show resolved Hide resolved

kbatuigas and others added 8 commits March 30, 2026 14:01

Add GBAC examples to rpk reference

fe1cc7a

Fix examples that used --print-groups

7e751bc

Conditionalize Cloud xrefs

5282667

Apply suggestions from doc review

3291dd6

Remove k8s

324320e

Standardize rpk formatting

c6c849f

Add Cloud UI instructions for groups registration and OIDC claims setup

b444e90

Merge branch 'v-WIP/26.1' into gbac

ed186b1

Feediver1 reviewed Mar 31, 2026

View reviewed changes

modules/manage/partials/gbac-dp.adoc Show resolved Hide resolved

Change ordering per SME suggestion

772bb24

kbatuigas and others added 2 commits March 30, 2026 21:06

Update local-antora-playbook.yml

9ae4d69

Superuser not available in Cloud

c2263bf

david-yu mentioned this pull request Mar 31, 2026

docs (k8s): Manage Groups and ACLs with the Redpanda Operator #1639

Merged

4 tasks

kbatuigas merged commit 0a5e0e8 into v-WIP/26.1 Mar 31, 2026
7 checks passed

kbatuigas deleted the gbac branch March 31, 2026 04:49

		@@ -0,0 +1,336 @@
		// tag::single-source[]

		Group-based access control (GBAC) builds on xref:manage:security/authorization/rbac.adoc[role-based access control (RBAC)] to simplify permission management at scale. Instead of assigning roles or ACLs to individual users, you assign them to OIDC groups managed by your identity provider (IdP). Users inherit permissions from all groups reported in their OIDC token claims, so onboarding and offboarding require no changes in Redpanda.

	This example shows an API Activity event (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:manage:security/authorization/gbac.adoc[].
	This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:manage:security/authorization/gbac.adoc[].

Conversation

paulohtb6 commented Feb 24, 2026 • edited by micheleRP Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Page previews

Checks

Uh oh!

netlify bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for redpanda-docs-preview ready!

Uh oh!

coderabbitai bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

nguyen-andrew left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

treevon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nguyen-andrew left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

graham-rp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

micheleRP commented Mar 30, 2026

Uh oh!

micheleRP left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

david-yu commented Mar 31, 2026

Uh oh!

kbatuigas commented Mar 31, 2026

Uh oh!

paulohtb6 commented Feb 24, 2026 •

edited by micheleRP

Loading

netlify bot commented Feb 24, 2026 •

edited

Loading

coderabbitai bot commented Feb 24, 2026 •

edited

Loading

kbatuigas commented Mar 31, 2026 •

edited

Loading